<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Http_Client - Advanced Usage - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.http.client.advanced.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.http.client.advanced.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.http.client.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.http.html">Zend_Http</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.http.client.adapters.html">Zend_Http_Client - Connection Adapters</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.http.client.advanced" class="section"><div class="info"><h1 class="title">Zend_Http_Client - Advanced Usage</h1></div>
    

    <div class="section" id="zend.http.client.redirections"><div class="info"><h1 class="title">HTTP Redirections</h1></div>
        

        <p class="para">
            By default, <span class="classname">Zend_Http_Client</span> automatically handles
            <acronym class="acronym">HTTP</acronym> redirections, and will follow up to 5 redirections. This can be
            changed by setting the &#039;maxredirects&#039; configuration parameter.
        </p>

        <p class="para">
            According to the <acronym class="acronym">HTTP</acronym>/1.1 RFC, <acronym class="acronym">HTTP</acronym> 301 and 302
            responses should be treated by the client by resending the same request to the
            specified location - using the same request method. However, most
            clients to not implement this and always use a <b><tt>GET</tt></b> request when
            redirecting. By default, <span class="classname">Zend_Http_Client</span> does the same - when
            redirecting on a 301 or 302 response, all <b><tt>GET</tt></b> and POST parameters
            are reset, and a <b><tt>GET</tt></b> request is sent to the new location. This
            behavior can be changed by setting the &#039;strictredirects&#039; configuration
            parameter to boolean <b><tt>TRUE</tt></b>:
            <div class="example" id="zend.http.client.redirections.example-1"><div class="info"><p><b>Example #1 Forcing RFC 2616 Strict Redirections on 301 and 302 Responses</b></p></div>
                

                <pre class="programlisting brush: php">
// Strict Redirections
$client-&gt;setConfig(array(&#039;strictredirects&#039; =&gt; true));

// Non-strict Redirections
$client-&gt;setConfig(array(&#039;strictredirects&#039; =&gt; false));
</pre>

            </div>
        </p>

        <p class="para">
            You can always get the number of redirections done after sending a
            request using the getRedirectionsCount() method.
        </p>
    </div>

    <div class="section" id="zend.http.client.cookies"><div class="info"><h1 class="title">Adding Cookies and Using Cookie Persistence</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Http_Client</span> provides an easy interface for adding cookies
            to your request, so that no direct header modification is
            required. This is done using the setCookie() method. This method
            can be used in several ways:

            <div class="example" id="zend.http.client.cookies.example-1"><div class="info"><p><b>Example #2 Setting Cookies Using setCookie()</b></p></div>
                

                <pre class="programlisting brush: php">
// Easy and simple: by providing a cookie name and cookie value
$client-&gt;setCookie(&#039;flavor&#039;, &#039;chocolate chips&#039;);

// By directly providing a raw cookie string (name=value)
// Note that the value must be already URL encoded
$client-&gt;setCookie(&#039;flavor=chocolate%20chips&#039;);

// By providing a Zend_Http_Cookie object
$cookie = Zend_Http_Cookie::fromString(&#039;flavor=chocolate%20chips&#039;);
$client-&gt;setCookie($cookie);
</pre>

            </div>

            For more information about <span class="classname">Zend_Http_Cookie</span> objects, see
            <a href="zend.http.cookies.html" class="link">this section</a>.
        </p>

        <p class="para">
            <span class="classname">Zend_Http_Client</span> also provides the means for cookie stickiness -
            that is having the client internally store all sent and received
            cookies, and resend them automatically on subsequent requests. This
            is useful, for example when you need to log in to a remote site
            first and receive and authentication or session ID cookie before
            sending further requests.

            <div class="example" id="zend.http.client.cookies.example-2"><div class="info"><p><b>Example #3 Enabling Cookie Stickiness</b></p></div>
                

                <pre class="programlisting brush: php">
// To turn cookie stickiness on, set a Cookie Jar
$client-&gt;setCookieJar();

// First request: log in and start a session
$client-&gt;setUri(&#039;http://example.com/login.php&#039;);
$client-&gt;setParameterPost(&#039;user&#039;, &#039;h4x0r&#039;);
$client-&gt;setParameterPost(&#039;password&#039;, &#039;1337&#039;);
$client-&gt;request(&#039;POST&#039;);

// The Cookie Jar automatically stores the cookies set
// in the response, like a session ID cookie.

// Now we can send our next request - the stored cookies
// will be automatically sent.
$client-&gt;setUri(&#039;http://example.com/read_member_news.php&#039;);
$client-&gt;request(&#039;GET&#039;);
</pre>

            </div>

            For more information about the <span class="classname">Zend_Http_CookieJar</span> class, see
            <a href="zend.http.cookies.html#zend.http.cookies.cookiejar" class="link">this section</a>.
        </p>
    </div>

    <div class="section" id="zend.http.client.custom_headers"><div class="info"><h1 class="title">Setting Custom Request Headers</h1></div>
        

        <p class="para">
            Setting custom headers can be done by using the setHeaders() method.
            This method is quite diverse and can be used in several ways, as
            the following example shows:

            <div class="example" id="zend.http.client.custom_headers.example-1"><div class="info"><p><b>Example #4 Setting A Single Custom Request Header</b></p></div>
                

                <pre class="programlisting brush: php">
// Setting a single header, overwriting any previous value
$client-&gt;setHeaders(&#039;Host&#039;, &#039;www.example.com&#039;);

// Another way of doing the exact same thing
$client-&gt;setHeaders(&#039;Host: www.example.com&#039;);

// Setting several values for the same header
// (useful mostly for Cookie headers):
$client-&gt;setHeaders(&#039;Cookie&#039;, array(
    &#039;PHPSESSID=1234567890abcdef1234567890abcdef&#039;,
    &#039;language=he&#039;
));
</pre>

            </div>
        </p>

        <p class="para">
            setHeader() can also be easily used to set multiple headers in one
            call, by providing an array of headers as a single parameter:

            <div class="example" id="zend.http.client.custom_headers.example-2"><div class="info"><p><b>Example #5 Setting Multiple Custom Request Headers</b></p></div>
                

                <pre class="programlisting brush: php">
// Setting multiple headers, overwriting any previous value
$client-&gt;setHeaders(array(
    &#039;Host&#039; =&gt; &#039;www.example.com&#039;,
    &#039;Accept-encoding&#039; =&gt; &#039;gzip,deflate&#039;,
    &#039;X-Powered-By&#039; =&gt; &#039;Zend Framework&#039;));

// The array can also contain full array strings:
$client-&gt;setHeaders(array(
    &#039;Host: www.example.com&#039;,
    &#039;Accept-encoding: gzip,deflate&#039;,
    &#039;X-Powered-By: Zend Framework&#039;));
</pre>

            </div>
        </p>
    </div>

    <div class="section" id="zend.http.client.file_uploads"><div class="info"><h1 class="title">File Uploads</h1></div>
        

        <p class="para">
            You can upload files through <acronym class="acronym">HTTP</acronym> using the setFileUpload method.
            This method takes a file name as the first parameter, a form name
            as the second parameter, and data as a third optional parameter.
            If the third data parameter is <b><tt>NULL</tt></b>, the first file name parameter
            is considered to be a real file on disk, and <span class="classname">Zend_Http_Client</span>
            will try to read this file and upload it. If the data parameter is not
            <b><tt>NULL</tt></b>, the first file name parameter will be sent as the file name,
            but no actual file needs to exist on the disk.
            The second form name parameter is always required, and is equivalent
            to the &quot;name&quot; attribute of an &gt;input&lt; tag, if the file was to
            be uploaded through an <acronym class="acronym">HTML</acronym> form.
            A fourth optional parameter provides the file&#039;s content-type. If
            not specified, and <span class="classname">Zend_Http_Client</span> reads the file from the disk,
            the mime_content_type function will be used to guess the file&#039;s
            content type, if it is available. In any case, the default MIME
            type will be application/octet-stream.
            <div class="example" id="zend.http.client.file_uploads.example-1"><div class="info"><p><b>Example #6 Using setFileUpload to Upload Files</b></p></div>
                

                <pre class="programlisting brush: php">
// Uploading arbitrary data as a file
$text = &#039;this is some plain text&#039;;
$client-&gt;setFileUpload(&#039;some_text.txt&#039;, &#039;upload&#039;, $text, &#039;text/plain&#039;);

// Uploading an existing file
$client-&gt;setFileUpload(&#039;/tmp/Backup.tar.gz&#039;, &#039;bufile&#039;);

// Send the files
$client-&gt;request(&#039;POST&#039;);
</pre>

            </div>

            In the first example, the $text variable is uploaded and will be
            available as $_FILES[&#039;upload&#039;] on the server side. In the second
            example, the existing file /tmp/Backup.tar.gz is uploaded to the
            server and will be available as $_FILES[&#039;bufile&#039;]. The content type
            will be guesses automatically if possible - and if not, the content
            type will be set to &#039;application/octet-stream&#039;.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Uploading files</b><br /></span>
            

            <p class="para">
                When uploading files, the <acronym class="acronym">HTTP</acronym> request content-type is
                automatically set to multipart/form-data. Keep in mind that
                you must send a POST or PUT request in order to upload files.
                Most servers will ignore the requests body on other request
                methods.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.http.client.raw_post_data"><div class="info"><h1 class="title">Sending Raw POST Data</h1></div>
        

        <p class="para">
            You can use a <span class="classname">Zend_Http_Client</span> to send raw POST data using the
            setRawData() method. This method takes two parameters: the first
            is the data to send in the request body. The second optional
            parameter is the content-type of the data. While this parameter is
            optional, you should usually set it before sending the request -
            either using setRawData(), or with another method: setEncType().

            <div class="example" id="zend.http.client.raw_post_data.example-1"><div class="info"><p><b>Example #7 Sending Raw POST Data</b></p></div>
                

                <pre class="programlisting brush: php">
$xml = &#039;&lt;book&gt;&#039; .
       &#039;  &lt;title&gt;Islands in the Stream&lt;/title&gt;&#039; .
       &#039;  &lt;author&gt;Ernest Hemingway&lt;/author&gt;&#039; .
       &#039;  &lt;year&gt;1970&lt;/year&gt;&#039; .
       &#039;&lt;/book&gt;&#039;;

$client-&gt;setRawData($xml, &#039;text/xml&#039;)-&gt;request(&#039;POST&#039;);

// Another way to do the same thing:
$client-&gt;setRawData($xml)-&gt;setEncType(&#039;text/xml&#039;)-&gt;request(&#039;POST&#039;);
</pre>

            </div>

            The data should be available on the server side through <acronym class="acronym">PHP</acronym>&#039;s
            $HTTP_RAW_POST_DATA variable or through the php://input stream.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Using raw POST data</b><br /></span>
            

            <p class="para">
                Setting raw POST data for a request will override any POST
                parameters or file uploads. You should not try to use both on
                the same request. Keep in mind that most servers will ignore
                the request body unless you send a POST request.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.http.client.http_authentication"><div class="info"><h1 class="title">HTTP Authentication</h1></div>
        

        <p class="para">
            Currently, <span class="classname">Zend_Http_Client</span> only supports basic
            <acronym class="acronym">HTTP</acronym> authentication. This feature is utilized using the
             <span class="methodname">setAuth()</span> method, or by specifying a username and a password in
            the URI. The  <span class="methodname">setAuth()</span> method
            takes 3 parameters: The user name, the password and an optional
            authentication type parameter. As mentioned, currently only basic
            authentication is supported (digest authentication support is
            planned).

            <div class="example" id="zend.http.client.http_authentication.example-1"><div class="info"><p><b>Example #8 Setting HTTP Authentication User and Password</b></p></div>
                

                <pre class="programlisting brush: php">
// Using basic authentication
$client-&gt;setAuth(&#039;shahar&#039;, &#039;myPassword!&#039;, Zend_Http_Client::AUTH_BASIC);

// Since basic auth is default, you can just do this:
$client-&gt;setAuth(&#039;shahar&#039;, &#039;myPassword!&#039;);

// You can also specify username and password in the URI
$client-&gt;setUri(&#039;http://christer:secret@example.com&#039;);
</pre>

            </div>
        </p>
    </div>

    <div class="section" id="zend.http.client.multiple_requests"><div class="info"><h1 class="title">Sending Multiple Requests With the Same Client</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Http_Client</span> was also designed specifically to handle several
            consecutive requests with the same object. This is useful in cases
            where a script requires data to be fetched from several places, or
            when accessing a specific <acronym class="acronym">HTTP</acronym> resource requires logging in and
            obtaining a session cookie, for example.
        </p>

        <p class="para">
            When performing several requests to the same host, it is highly
            recommended to enable the &#039;keepalive&#039; configuration flag. This way,
            if the server supports keep-alive connections, the connection to the
            server will only be closed once all requests are done and the Client
            object is destroyed. This prevents the overhead of opening and
            closing <acronym class="acronym">TCP</acronym> connections to the server.
        </p>

        <p class="para">
            When you perform several requests with the same client, but want
            to make sure all the request-specific parameters are cleared, you
            should use the resetParameters() method. This ensures that <b><tt>GET</tt></b> and
            POST parameters, request body and request-specific headers are
            reset and are not reused in the next request.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Resetting parameters</b><br /></span>
            

            <p class="para">
                Note that non-request specific headers are not reset by default
                when the  <span class="methodname">resetParameters()</span> method is used.
                Only the &#039;Content-length&#039; and &#039;Content-type&#039; headers are reset. This
                allows you to set-and-forget headers like &#039;Accept-language&#039; and
                &#039;Accept-encoding&#039;
            </p>

            <p class="para">
                To clean all headers and other data except for URI and method, use
                 <span class="methodname">resetParameters(true)</span>.
            </p>
        </p></blockquote>

        <p class="para">
            Another feature designed specifically for consecutive requests is
            the Cookie Jar object. Cookie Jars allow you to automatically save
            cookies set by the server in the first request, and send them on
            consecutive requests transparently. This allows, for example, going
            through an authentication request before sending the actual data
            fetching request.
        </p>

        <p class="para">
            If your application requires one authentication request per user,
            and consecutive requests might be performed in more than one script
            in your application, it might be a good idea to store the Cookie Jar
            object in the user&#039;s session. This way, you will only need to
            authenticate the user once every session.
        </p>

        <div class="example" id="zend.http.client.multiple_requests.example-1"><div class="info"><p><b>Example #9 Performing consecutive requests with one client</b></p></div>
            

            <pre class="programlisting brush: php">
// First, instantiate the client
$client = new Zend_Http_Client(&#039;http://www.example.com/fetchdata.php&#039;, array(
    &#039;keepalive&#039; =&gt; true
));

// Do we have the cookies stored in our session?
if (isset($_SESSION[&#039;cookiejar&#039;]) &amp;&amp;
    $_SESSION[&#039;cookiejar&#039;] instanceof Zend_Http_CookieJar) {

    $client-&gt;setCookieJar($_SESSION[&#039;cookiejar&#039;]);
} else {
    // If we don&#039;t, authenticate and store cookies
    $client-&gt;setCookieJar();
    $client-&gt;setUri(&#039;http://www.example.com/login.php&#039;);
    $client-&gt;setParameterPost(array(
        &#039;user&#039; =&gt; &#039;shahar&#039;,
        &#039;pass&#039; =&gt; &#039;somesecret&#039;
    ));
    $client-&gt;request(Zend_Http_Client::POST);

    // Now, clear parameters and set the URI to the original one
    // (note that the cookies that were set by the server are now
    // stored in the jar)
    $client-&gt;resetParameters();
    $client-&gt;setUri(&#039;http://www.example.com/fetchdata.php&#039;);
}

$response = $client-&gt;request(Zend_Http_Client::GET);

// Store cookies in session, for next page
$_SESSION[&#039;cookiejar&#039;] = $client-&gt;getCookieJar();
</pre>

        </div>
    </div>

    <div class="section" id="zend.http.client.streaming"><div class="info"><h1 class="title">Data Streaming</h1></div>
        

        <p class="para">
            By default, <span class="classname">Zend_Http_Client</span> accepts and returns data as
            <acronym class="acronym">PHP</acronym> strings. However, in many cases there are big files to be sent or
            received, thus keeping them in memory might be unnecessary or too expensive. For these
            cases, <span class="classname">Zend_Http_Client</span> supports reading data from files (and in
            general, <acronym class="acronym">PHP</acronym> streams) and writing data to files (streams).
        </p>

        <p class="para">
            In order to use stream to pass data to <span class="classname">Zend_Http_Client</span>,
            use  <span class="methodname">setRawData()</span> method with data argument being stream
            resource (e.g., result of  <span class="methodname">fopen()</span>).

            <div class="example" id="zend.http.client.streaming.example-1"><div class="info"><p><b>Example #10 Sending file to HTTP server with streaming</b></p></div>
                

                <pre class="programlisting brush: php">
$fp = fopen(&quot;mybigfile.zip&quot;, &quot;r&quot;);
$client-&gt;setRawData($fp, &#039;application/zip&#039;)-&gt;request(&#039;PUT&#039;);
</pre>

            </div>
        </p>

        <p class="para">
            Only PUT requests currently support sending streams to <acronym class="acronym">HTTP</acronym> server.
        </p>

        <p class="para">
            In order to receive data from the server as stream, use
             <span class="methodname">setStream()</span>. Optional argument specifies the filename where the
            data will be stored. If the argument is just <b><tt>TRUE</tt></b> (default),
            temporary file will be used and will be deleted once response object is destroyed.
            Setting argument to <b><tt>FALSE</tt></b> disables the streaming functionality.
        </p>

        <p class="para">
            When using streaming,  <span class="methodname">request()</span> method will return object of
            class <span class="classname">Zend_Http_Client_Response_Stream</span>, which has two useful
            methods:  <span class="methodname">getStreamName()</span> will return the name of the file where
            the response is stored, and  <span class="methodname">getStream()</span> will return stream from
            which the response could be read.
        </p>

        <p class="para">
            You can either write the response to pre-defined file, or use temporary file for storing
            it and send it out or write it to another file using regular stream functions.

            <div class="example" id="zend.http.client.streaming.example-2"><div class="info"><p><b>Example #11 Receiving file from HTTP server with streaming</b></p></div>
                

                <pre class="programlisting brush: php">
$client-&gt;setStream(); // will use temp file
$response = $client-&gt;request(&#039;GET&#039;);
// copy file
copy($response-&gt;getStreamName(), &quot;my/downloads/file&quot;);
// use stream
$fp = fopen(&quot;my/downloads/file2&quot;, &quot;w&quot;);
stream_copy_to_stream($response-&gt;getStream(), $fp);
// Also can write to known file
$client-&gt;setStream(&quot;my/downloads/myfile&quot;)-&gt;request(&#039;GET&#039;);
</pre>

            </div>
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.http.client.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.http.html">Zend_Http</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.http.client.adapters.html">Zend_Http_Client - Connection Adapters</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.http.html">Zend_Http</a></li>
  <li><a href="zend.http.client.html">Introduction</a></li>
  <li class="active"><a href="zend.http.client.advanced.html">Zend_Http_Client - Advanced Usage</a></li>
  <li><a href="zend.http.client.adapters.html">Zend_Http_Client - Connection Adapters</a></li>
  <li><a href="zend.http.cookies.html">Zend_Http_Cookie and Zend_Http_CookieJar</a></li>
  <li><a href="zend.http.response.html">Zend_Http_Response</a></li>
  <li><a href="zend.http.user-agent.html">Zend_Http_UserAgent</a></li>
  <li><a href="zend.http.user-agent-device.html">The UserAgent Device Interface</a></li>
  <li><a href="zend.http.user-agent-features.html">The UserAgent Features Adapter</a></li>
  <li><a href="zend.http.user-agent-features-wurfl.html">The WURFL UserAgent Features Adapter</a></li>
  <li><a href="zend.http.user-agent-features-device-atlas.html">The DeviceAtlas UserAgent Features Adapter</a></li>
  <li><a href="zend.http.user-agent-features-tera-wurfl.html">The TeraWurfl UserAgent Features Adapter</a></li>
  <li><a href="zend.http.user-agent-storage.html">The UserAgent Storage Interface</a></li>
  <li><a href="zend.http.user-agent-storage-session.html">The Session UserAgent Storage Adapter</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>